docs: port missing best-practices content from portal#246
Draft
marc0olo wants to merge 7 commits into
Draft
Conversation
Five gaps ported from dfinity/portal building-apps/best-practices/: - Extend app-architecture.md with canister-per-user pattern including the honest note that no successful end-to-end implementation exists yet and the misconception correction (per-subnet is more scalable) - New trust-in-canisters.md guide: two-question trust framework, Wasm hash verification, canister history, controller verification, trust spectrum (developer to multi-sig to SNS to black-holed), black hole canister caveat for self-reinstalling code - Extend data-persistence.mdx: Storage recommendations section with heap-vs-stable decision table, mo:core data structure guidance, Rust cautions, state backup, transaction history patterns - New pagination.md guide: cursor-based pagination for mutable datasets, handling deleted cursors, sort order stability - New troubleshooting.md guide: rewritten for icp CLI; latency diagnosis, compute allocation, CSP fix, Wasm import errors; dfx-era content excluded - Cross-links added in reproducible-builds.md and canister-control.md
|
🤖 Here's your preview: https://keluh-vqaaa-aaaam-ai7wa-cai.icp0.io |
- Fix Map.entries() call in pagination.md Motoko example (no comparator arg) - Remove unused import Iter in pagination.md - Add sidebar orders to pagination.md (6), idempotency.md (5), trust-in-canisters.md (11), troubleshooting.md (12); orders 11-12 leave room for canister-migration.md (10) from PR #245 - Add subnet migration subsection to troubleshooting.md latency problem - Fix icp canister status flag: -n ic -> -e ic in trust-in-canisters.md - Link SNS term in trust spectrum table to concepts/sns-framework.md - Add pagination.md to inter-canister-calls.mdx Next steps
Member
Author
|
Review fixes applied:
Merge dependency on #245: Merge #245 first. Before merging this PR, update troubleshooting.md line 46: change |
Validation script requires hand-written, sync from, or informed by. Changed "ported from" and "rewritten (not ported) from" to "informed by" in pagination.md, trust-in-canisters.md, and troubleshooting.md.
- Motoko: Array.append does not exist in mo:core/Array; replace with Array.concat - Rust: Item struct used as StableBTreeMap value requires Storable impl; add it using ciborium CBOR serialization, consistent with stable-structures.md pattern
Member
Author
|
Review fixes applied (second round — code correctness):
|
Spawning a user canister carries the same overhead as a fresh canister install. This was in the portal storage.mdx efficiency recommendations but belongs here alongside the other canister-per-user caveats.
Member
Author
|
Review fix applied (portal gap — actor class instantiation cost): Added a bullet to the canister-per-user "Things to know" list in
Source: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #241
Summary
concepts/app-architecture.md, including the honest note that no successful end-to-end implementation exists yet and the correction of the scalability misconception (per-subnet is more performant than per-user)guides/canister-management/trust-in-canisters.md— cohesive user-facing trust assessment guide: two-question framework, Wasm hash verification, canister history tracking, controller verification viaicp canister status, trust spectrum table (developer-controlled → multi-sig → SNS → black-holed), black hole canister details, and caveat for self-reinstalling canistersguides/backends/data-persistence.mdxwith a "Storage recommendations" section: heap-vs-stable decision table, mo:core data structure guidance (Map, List, Queue, pure/Map, pure/Set), Rust cautions on Vec/String serialization, state backup strategies, transaction history patternsguides/canister-calls/pagination.md— cursor-based pagination for mutable datasets, with Motoko and Rust examples, handling deleted cursors, and sort order stability notesguides/canister-management/troubleshooting.md— fully rewritten foricpCLI; covers network latency, subnet load identification, compute allocation, boundary node info for support escalation, heap-vs-stable latency, inter-canister call optimization, frontend CSP violations,.ic-assets.json5security policy warnings, and Rust Wasm import errors. All dfx-era content (cycles wallet, dfxvm, WSL) excluded.reproducible-builds.mdandcanister-control.mdto the new trust guideSync recommendation
informed by dfinity/portal — docs/building-apps/best-practices/application-architectures.mdx, trust-in-canisters.mdx, storage.mdx, general.mdx (pagination item), troubleshooting.mdx